6 INTERRUPT PROCESSING 


Section 6 describes system actions for the various Interrupt 
causing events* defines the mang RAM vectors and provides 
recommended procedures for dealing with Interrupts. 

The 6502 microcomputer processes three general Interrupt tgpes: 
chip-reset, nonmaskable interrupts (NMI) and maskable Interrupt 
<IRQ). The IRQ Interrupt type can be enabled and disabled using 
the 6502 CLI and SEI instructions. The NMI type cannot be 
disabled at the processor level; but the NMI interrupts other 
than ESYSTEM. RESET3 key can be disabled at the ANTIC Chip. 


The System events that can cause interrupts are listed below: 
chip-reset - pomer-up 

NMI - Display list Interrupt (unused by OS) 
vertical-blank <50/60 Hz) 

ESYSTEM. RESET3 key 

IRQ - Serial bus output ready 

Serial bus output complete 
Serial bus input ready 

Serial bus proceed line (unused by System) 

Serial bus interrupt line (unused by System) 

PQKEY timers 1, 2 and 4 
Keyboard key 
EBREAK3 key 

6502 BRK instruction (unused by OS) 


Figure 6-i List of System-Interrupt Events 
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The chip-reset interrupt is vectored via location FFFC to E477. 
where a JMP vector to the power-up routine is located. All NMI 
interrupts are vectored via location FFFA to the NMI interrupt 
Service routine at E7B4» and all IRQ interrupts are vectored 
via location FFFE to the IRQ interrupt Service routine at E6F3; 
at that point the cause of the interrupt must be determined by 
a series of tests. For some of the events there are built in 
monitor actions and for other events the corresponding 
interrupts are disabled or ignored. The System provides RAM 
vectors so that you can intercept interrupts tuhen 
necessary. 


CHIP-RESET 

The ÖS generates chip-reset in response to a power-up condition. 
The System is compietely initialized (see Section 7). 


NGNMASKABLE INTERRUPTS 

When an NMI interrupt occurs» control is transferred through 
the ROM vector directly to the System NMI interrupt service 
routine. A cause for the interrupt is determined by examining 
Hardware register NMIST CD40FJ. The NMI makes a jump through the 
global RAM vector VDSLST C030Q1 if a dispiay list interrupt is 
pending. The ÖS does not use dispiay list Interrupts» so VDSLST 
is initialized to point to an RTI instruction» and you must not 
change it before VDSLST generates a dispiay interrupt. 

If the interrupt is not a display-list interrupt» then a test is 
made to see if it is a CSYSTEM.RESET3 key interrupt. If soi then a 
jump is made to the system reset initialization routine (see Section 
7 for details of system reset initialization). 

If the interrupt is neither a dispiay list interrupt nor a 
CSYSTEM.RESET1 key interrupt; then it is assumed to be a 
vertica1-blank (VBLANK) interrupt» and the following actions 
occur: 

Registers A» X and Y are pushed to the stack. 

The interrupt reyuest is cleared (NMIRES CD40F3). 

A jump is made through the ** immed iate" ver t ica 1-b lank global 
RAM vector VVBLKI CQ222J that normally points to the Stage 1 
VBLANK processor. 

The following actions occur assuming that you have not changed VVBLKI. 
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The stage 1 VBLANK processor is executed. 

The OS tests to see if a critical code section has been 
interrupted. If so» then all registers are restored» and an 
RTI instruction returns from the interrupt to the critical 
section. A critical section is determined by examining the 
CRITIC flag CQ0423, and the processor I bit. If either are 
set» then the interrupted section is assumed to be critical. 

If the interrupt was not from a critical section» then the 
stage 2 VBLANK processor is executed. 

The OS then jumps through the “deferred" vertical-blank 
global RAM vector VBLKD C02243, that normally points to the 
VBLANK exit routine. 

The following actions occur assuming that you have not changed VVBLKD. 
o The 6502 A»X and Y registers are restored. 
o An RTI instruction is executed. 


NOTE: You can alter the deferred and immediate 

VBLANK RAM vectors, but still enable normal System processesi or 
restore original vectors without having to save them. The 
instruction at E45F is a JMP to the stage 1 VBLANK processor» the 
address at CE460»23 is the value normally found in VVBLKI. The 
instruction at E462 is a JMP to the VBLANK exit routine» the 
address at CE463»23 is the value normally found in VVBLKD. These 
ROM vectors to stage 1 VBLANK processor and to the VBLANK exit 
routine will accomplish your goal. 

NOTE: Every VBLANK interrupt jumps through vector VVBLKI. önly 

VBLANK interrupts from noncritical code sections jump through 
vector VVBLKD. 


Stage i VBLANK Process 

The following stage 1 VBLANK processing is performed at every 
VBLANK interrupt: 

The stage 1 VBLANK process increments the 3-byte frame 
counter RTCLOK 10012-00141» RTCLOK+O is the MSB and RTCLÜK+2 
is the LSB. This counter wraps to zero when it overflows 
(every 77 hours or so}, and continues counting. 

The Attract mode variables are processed (see Appendix L, 
BIO-12). 

The stage 1 VBLANK process decrements the System Timer 1 
CDTMV1 10218,23 if it is nonzero; if the timer goes from 
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nonzero to zero then an indirect JSR is performed via CDTMA1 
£0226, 23. 


Stage 2 VBLANK Process 

The stage 2 VBLANK Processing performs the following for those 
VBLANK Interrupts that do not interrupt critical sections: 

The stage 2 VBLANK process clears the 6502 processor I bit. 
This enables the IRQ interrupts. 

The stage 2 VBLANK process Updates various hardware 
registers uith data front the OS data base, as shown belout: 


Data Base 

Hardware 

Reason 

for Update 

Item 


Register 



SDLSTH 

£02313 

DLISTH 

£ D4033 

Display 

list start 

SDLSTL 

£02303 

DLISTL 

£04023 


SDMCTL 

£022F3 

DMACTL 

£04003 



CHBAS 

C02F43 

CHBASE 

£04093 



CH ACT 

C02F33 

CHACTL 

ED4013 



GPRIOR 

£Ö26F3 

PRIOR 

£ DO1B 3 



COLORO 

C02C43 

COLPFO 

£00163 

Attrac t 

mode. 

C0LQR1 

E02C53 

C0LPF1 

£00173 



C0L0R2 

£02063 

C0LPF2 

£00183 



C0L0R3 

E02C73 

C0LPF3 

£00193 



C0L0R4 

£02083 

COLBK 

£ 001A 3 



PCQLRQ 

E02C03 

COLPMO 

£00123 



PCÖLRi 

£02013 

C0LPM1 

£00133 



PCQLR2 

£02023 

C0LPM2 

£00143 



PC0LR3 

C02C33 

C0LPM3 

£00153 



Constant = 8 

CONSOL 

ED01F3 

Consale 

Speaker off 


The stage 2 VBLANK process decrements the System Timer 2 
CDTMV2 E021A,23 if it is nonzero; if the timer goes front 
nonzero to zero, then an indirect JSR is performed 
through CDTMA2 £0228, 23. 


The stage 2 VBLANK process decrements System Timers 3, 4 and 
5 if they are nonzero; the corresponding flags are set to 
zero for each timer that changes from nonzero to zero. 
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Timer 


Timer Value 


Timer Flag 


3 CDTMV3 C021C,23 CDTMF3 £022A,13 

4 CDTMV4 C021£> 23 CDTMF4 £022C,13 

5 CDTMV5 £0220.23 CDTMF5 £022E,I3 


A character is read froro the POKEY keyboard register and 
stored in CH £02FC3i if auto repeat is active. 

The stage 2 VBLANK process decrements the keyboard debounce 
counter if it is not egual to zero. and if no keg is 
pressed. 

The stage 2 VBLANK process processes the kegboard auto 
repeat (see Appendix Li E8>. 

The stage 2 VBLANK process reads game Controller data from 
the hardware to the RAM data base, as shoum below: 


Hardware 

Oata Base 

Function 

Register 

Item 



PORTA 

£03003 

STICKO 

£02783 

Joysticks and 



STICK1 

£02793 




PTRIGO 

£02703 

Paddle Controllers 



PTRIG1 

£Ö27D3 




PTRIG2 

£027E3 




PTRIG3 

£027F3 


PORTB 

£03013 

STICK2 

£027A3 




STICK3 

£027B 3 




PTRIG4 

£02803 




PTRIG5 

£02813 




PTRIG6 

£02823 




PTRIG7 

£02833 


POT 0 

£02003 

PADDLO 

£02703 

Paddle Controllers 

POT 1 

£02013 

PADDL1 

£02713 


POT 2 

£02023 

PADDL2 

£02723 


POT 3 

£02033 

PA0DL3 

£02733 


POT 4 

£02043 

PADDL4 

£02743 


POT 5 

£02053 

PADDL5 

£02753 


POT 6 

£02063 

PADDL6 

£02763 


POT 7 

£02073 

PADDL7 

£02773 


TR IGO 

£0001 3 

STR IGO 

£02843 

Joystick triggers. 

TRI Gl 

£00023 

STRIG1 

£02853 


TRIG2 

£00033 

STRIG2 

£02863 


TRIG3 

£00043 

STRIG3 

£02873 
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MASKABLE INTERRUPTS 


An IRQ Interrupt causes control to be transferred through the 
immediate IRQ global RAM vector VIMIRG C02163. Qrdinarily this 
vector points to the System IRQ Händler. The Händler performs 
these follobfing actions: 

The IRQ Händler determines a cause for the Interrupt by 
examining the IRQST CD2QE3 register and the PIA Status 
registers PACTL CD3023 and PBCTL CD3033. The interrupt status bit 
is cleared when it is found. One interrupt event is cleared and 
processed for each interrupt-service entry. If multiple IRQs are 
pending, then a separate interrupt will be generated for each 
pending IRQ, until all are serviced. 

The System IRQ interrupt service routine deals with each of the 
possible IRQ causing events, in the following ways: 

ü The 6502 A register is pushed to the stack. 

n If the interrupt is due to serial I/O bus output ready, 
then clear the interrupt and jump through global RAM 
vector VSEROR 102003. 

o If the interrupt is due to serial I/O bus input ready, 
then clear the interrupt and jump through global RAM 
vector USERIN C020A3. 

□ If the interrupt is due to serial I/O bus output 
complete, then clear the interrupt and jump through 
global RAM vector V5ER0C C020E3. 

□ If the interrupt is due to POKEY timer #1, then clear the 
interrupt and jump through global RAM vector VTIMR1 E02103. 

o If the interrupt is due to POKEY timer #2, then clear the 
interrupt and jump through global RAM vector VTIMR2 102123. 

o If the interrupt is due to POKEY timer #4, then clear the 
interrupt. The service routine contains a bug, and falls 
into the following test. 

o If pressing a keyboard key caused the interrupt (other 

than C BREAK 3, CSTART3, CQPTI0N3, or CSELECT3); then clear the 
interrupt and jump through global RAM vector VKEYBD E02083. 

o If pressing the t BREAK3 key caused the interrupt; then 

clear the interrupt. Set the BREAK flag BRKKEY C00113 to 
zero, proceed to clear the following: 

Start/stop flag SSFLAG C02FF3 
Cursor inhibit flag CRSINH C02F03 
Attract mode flag ATRACT C004D3 
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Return from the Interrupt after restoring the 6502 A 
register from the stack. 

o If the Interrupt is due to the serial I/O bus proceed line; 

then clear the Interrupt» and jump througb global RAM vector 
VPRCED £02021. 

o If the Interrupt is due to the serial I/O bus Interrupt 

line» then clear the Interrupt and jump through global RAM 
vector VINTER £02041. 

o If the Interrupt is due to a 6502 BRK instruction» then jump 
through global RAM vector VBREAK £02063. 

o If none of the above» restore the 6502 A register and return 
from the interrupt tRTI). 


INTERRUPT INITIALIZATION 

The interrupt subsgstem completely r e ini t ia 1 i zes itself tuhenever 
the System is powered up or the CSYSTEM. RESET3 key is pressed. 
The OS clears the hardware registers» and sets the interrupt 
global RAM vectors to the folloining configurations: 


Vector 


Type 

Func tion 

VDSLST 

£02003 

NMI 

RTI — ignore interrupt. 

VVBLKI 

£02221 

4t 

System stage 1 VBLANK. 

CDTMA1 

£02261 

II 

SIO timeout timer. 

CDTMA2 

£02281 

II 

No System function. 

VVBLKD 

£02243 

II 

System return from interrupt 

VIMIRG 

£02163 

IRQ 

System IRQ processor. 

VSEROR 

C020C1 

41 

SIÜ. 

VSERIN 

£020A3 

tl 

SIO. 

VSEROC 

CQ20E3 

44 

SIO. 

VTIMR1 

£02103 

44 

PLA»RTI — ignore interrupt. 

VTIMR2 

£02123 

4t 

PLA» RTI — ignore interrupt. 

VTIMR4 

£02143 

44 

doesn't matter 

VKEYBD 

£02081 

II 

System keyboard 
interrupt hand 1er, 

VPRCED 

£02021 

II 

PLA» RTI — ignore interrupt. 

VINTER 

£02041 

4t 

PLA» RTI — ignore interrupt. 

VBREAK 

£02061 

BRK 

PLA»RTI — ignore interrupt. 


Figure 6-2 Interrupt RAM Vector Initia1ization 


108 


OPERATINQ SYSTEM C016555 — Section 6 





System initialization sets the interrupt enable Status 
as follows: 

NMI VBLANK enabled, display list disabled. 

IRQ £BREAK3 key and data key interrupts enabledi all others 
disabled. 


SYSTEM TIMERS 

The OS contains five general purpose Software timers. plus an 
OS-supported frame counter. The timers are 2 bytes in length 
(loihi) and the frame counter RTCLOK EOÖ123 is three bytes in 
length (hi.mid > lo). The timers count downuiar d from any 
nonzero value to zero. Upon reaching zero, they either clear 
an associated flag. or JSR through a RAM vector. The frame 
counter counts upward. wrapping to zero tahen it Overflows. 

The following table shoins the timers and the frame counter 
charac teris tics: 


Timer Name Flag/Vector Use 


* CDTMV1 £02183 
CDTMV2 £021A3 
CDTMV3 £ 0210 3 
CDTMV4 £ 021E 3 
CDTMV5 £02203 
- RTCLOK £00123 


CDTMA1 £02263 
CDTMA2 £02283 
CDTMF3 £ 022A 3 
CDTMF4 E022C3 
CDTMF5 £022E3 


2-byte 

vec tor 

2-byte 

vec tor 

1-by te 

flag 

1-by te 

flag 

1-by te 

flag 

3-by te 

frame 


— SIO timeout. 


nter. 


* These two timers are maintained as part of every VBLANK 

interrupt (stage 1 process). The other timers are subject to 
the critical section test (stag e-2 process that can defer 
their updating to a later VBLANK interrupt. 


USAÖE NOTES 

This subsection describes the techniques you need to know in 
order to utilize interrupts in conjunction with the operating 
System. 
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POKEY Interrupt Mask 


ANTIC (display-1ist and vertical-blank) and PIA (interrupt and 
proceed lines) interrupts can be masked directly (see tbe 
Hardware Manual). However* eight bits qP a single byte IRGEN 
CD20ED mask the POKEY interrupts (CBREAK3 key* data key* 
serial input ready* serial output ready* serial output done 
and timers 1*2 and 4). 

IRGEN is a uir i te-an ly regist er. Thus* me must maintain a 
current value oP that register in RAM in order to update 
individual mask bits selectively* while not changing other bits. 
The name oP the variable used is POKMSK 10010 3* and it is used 
as shouin in the examples beloui: 


; EXAMPLE OF INTERRUPT ENABLE 


SEI 


i 

TO AVQID CONFLICT WITH IRQ 


LDA 

POKMSK 

i 

... PROCESSOR WHICH ALTERS 

VAR 

ORA 

#$xx 

t 

ENABLE BIT<S). 


STA 

POKMSK 




STA 

IRGEN 

i 

TO HARDWARE REG T00. 


CLI 





EXAMPLE OF 

INTERRUPT 

DISABLE 


SEI 


i 

TO AVQID CONFLICT WITH IRG 


LDA 

POKMSK 

i 

... PROCESSOR WHICH ALTERS 

VAR 

AND 

#*FF-xx 

i 

DISABLE BIT<S). 


STA 

POKMSK 




STA 

IRGEN 

j 

TO HARDWARE REGISTER T00. 



CLI 


Figure 6-3 POKEY Interrupt Mask Example 


Note that the OS IRQ Service routine uses and alters POKMSK* so 
alterations to the variable must be done uiith interrupts 
inhibited. IP done at the interrupt 1eve1 there is no prob lern* as 
the I bit is already set * i P done at a bac k ground level then the 
SEI and CLI instructions should be used as- shouin in the examples. 


Setting Interrupt and Timer Vectors 

Because vertica1-blank Interrupts are generally kept enabled so th 
the Prame counter RTCLOK is maintained accurately, there is a 
Problem uiith setting the VBLANK vectors (WBLKI and VVBLKD) or 
the timer values (CDTMV1 through CDTMV5) directly. A VBLANK 
interrupt could occur uihen only one byte oP the two-byte value had 
been updated* leading to undesired conseq,uences. For this reason* 
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the SETVBV EE45F3 routine is provided to perform the desired 
update in safe manner. The calling sequence is shouin belotif: 


A - update item indicator 
1-5 for timers 1-5. 

6 for immediate VBLANK vector VVBLKI. 

7 for deferred VBLANK vector VVBLKD. 

X — MSB of value to störe, 

Y =» LSB of value to störe. 

VSR SETVBV 

The A» X and Y registers can be altered. 

The display list interrupt will altuays be disabled on 
returni even if enabled upon entry. 

It is possible to fully process a vertical—blank interrupt 
during a call to this routine. 

Wh en ti/or fc ing titith the System T imersi the vec tor s f or timers 1 and 
2 and the flags for timers 3/ 4 and 5 should be set ü»h i le the 
associated timer is equal to zero, then the timer should be set 
to its (nonzero) value. 


Stack Content at Interrupt Vector Points 

The follouiing table shouis the stack content at every one of the 
RAM interrupt vector points: 
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RAM STACK CONTENT 

INTERRUPT VECTOR DESCRIPTIQN OS RETURN CONTROL 


VDSLST 

£02003 


Display list 

return. 

P 





VVBLKI 

102223 

* 

VBLANK immediate 

return. 

P, 

Ai 

X. 

Y 


CDTMA1 

Z 02263 


System Timer 1 

return. 

P, 

A, 

X. 

Y, 

return 

CDTMA2 

Z 02283 


System Timer 2 

return. 

P. 

A. 

X. 

Y. 

return 

WBLKD 

Z 02243 

* 

VBLANK defer. 

return. 

P, 

A, 

X, 

Y 


VIMIRG 

£02163 

# 

IRQ immediate 

return. 

P, 

A 




VSEROR 

C020C3 

* 

Serial out ready 

return. 

P. 

A 




USERIN 

£020A3 

* 

Serial in ready 

return. 

P, 

A 




VSEROC 

£020E3 


Serial out compare 

return. 

P, 

A 




VTIMR1 

£02103 


POKEY timer 1 

return. 

P. 

A 




VTIMR2 

£02123 


POKEY timer 2 

return. 

P. 

A 




VTIMR4 

£02143 


POKEY timer 4 

return. 

P, 

A 




VKEYBD 

£02083 

* 

Keyboard data 

return. 

P, 

A 




UPRSED 

£02023 


Serial proceed 

return. 

P, 

A 




VINTER 

£02043 


Serial interrupt 

return. 

P. 

A 




VBREAK 

£02063 


BRK instruction 

return. 

P. 

A 




Figure 6-4 

Interrupt 

and Timer Vector RAM 

Stack Content 

Table 



* The OS initializes these entries at power-up. Improperly 
changing these vectors will alter System performance. 


Misce1laneous Considerations 

The following paragraphs list a set of misc el laneous 
considerations for the writer of an Interrupt Service routine. 


Restrictions on Clearing of 'T' Bit 

Display list. immediate vertica1-falank and System Timer #1 
routines should not clear the 6502 I bit. If the NMI leading to 
one of these routines occurred while an IRQ was being processed. 
then Clearing the I bit will cause the IRQ to re-interrupt with 
an unknown result. 

The OS VBLANK processor carefully checks this condition after the 
stage 1 process and before the stage 2 process. 


Interrupt Process Time Restrictions 

You should not write an interrupt routine that exceeds 400 msec, 
when added to the stage i VBLANK. if the serial I/O is being 
used. The SIO sets the CRITIC flag while serial bus I/O is in 
progress. 
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Interrupt Delay Due ta "WAIT FOR SYNC" 

Whenever a key is read front the keyboardr the Keyboard Händler 
sets WSYNC CD40A3 repeatedly while generating the audible click 
on the console Speaker. A prob lern occurs when Interrupts are 
generated during the wait-for-sync periodi the processing of such 
Interrupts will be delayed by one horizontal scan line. This 
condition cannot be prevented. You can work around the condition 
by examining the line count VCOUNT CD40EU and delaying interrupt 
Processing by one line when no WSYNC delay has occurred. 


FLQWCHARTS 

The following pages contain process flowcharts showing the main 
events that occur in the NMI and IRQ interrupt processes. 


IRQ INTERRUPT PROCESS 
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7 SYSTEM INITIALIZATIQN 


Section 7 discusses the details of the power—up and 
System raset processes. The power-up process will he explained 
and then the System reset process will be explained in 
terms of its d i ff er enc es front the power-up process. 

Both power-up (also called coldstart) and pressing Z SYSTEM. RESET1 
(Warmstart) will cause System initia1ization: In addition, there 
are vectors for these processes at E474 (system reset) and E477 
(poutei up) so that they can be user-initiated. 


The powei up initialization process is a superset of the 
System reset initia1ization process. Pouer-up initializes both 
the OS and user RAM rsgions- whereas System reset initializes 
only the OS RAM region. In both cases, the OS calls the outer 
level Software initialization entry points allou the application 
to initialize its own variables. 

Pressing the CSYSTEM. RESET3 key produces an NMI interrupt. It 
does not perform a 6502 chip-reset. If the processor is locked 
up, the CSYSTEM.RESET3 key cannot be sufficient to unlock it, and the 
System must have power cycled to clear the problem. 


POWER-UP INITIALIZATION (COLDSTART) PROCEDURE 

The OS performs the following functions in the Order shown, as 
part of the power—up initia1ization process: 

1. The following 6502 processor states are set: 

o IRQ interrupts are disabled using the SEI instruction. 

o The decimal flag is cleared using the CLD instruction. 

o The stack pointer is set to *FF. 

2. The OS sets the Warmstart flag WÄRMST C000S3 to 0 (false) 
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3. The OS teste to see if a diagnostic cartridge is in the A slot; 

□ Cartridge address BFFC = 00? 

□ The memory at BFFC is not RAM? 

q Bit 7 of the byte at BFFD = 1? 


all of the above tests are true, then control is passed to 
the diagnostic cartridge via the vector at BFFE. No return is 
e xpec ted, 


4. The OS determines the 1 owest memory address containing 

non-RAM, by testing the first byte of every 4K “block" to see 
if the content can be complernented. If it can be complernented, 
then the origina1 value is restored and testing continues. 1f 
it can 't be comp1emented; then the content is assumed to be 
the first non-RAM address in the System. The MSB of the 
address is stored temporarily in TRAMSZ C000&]. 


5. Zero is stored to all of the harduare register addresses shown 
beiow (most of that aren ' t decoded by the hardware>: 

DOQG through DOFF 
D20Ö through D2FF 
D300 through D3FF 
D400 through D4FF 

6. The OS clears RAM front location 0008, to the address 
determined in step 4/ above. 

7. The default value for the “noncartridge" control vector 
DOSVEC C000A1 is set to point to the blackboard routine. At 
the end of initialization, control is passed through this 
vector if a cartridge does not take control. 

S. The coIdstart flag COLDST C02443 is set to -1 (local use). 

9. The screen margins are set: left margin = 2, right margin = 

39, for a 38 character physical line. The maximum line size of 
40 characters can be obtained by setting the margins to ö and 
39. The OS insets the left margin because the two 1 eftmost 

co1umns of the video picture on many televisian sets are not 
entirely visible on the screen. 

10. The interrupt RAM vectors VDSLST E02003 through VVBLKD C02241 
are initialized. See Section 6 for the initialization values, 

11. Portions of the OS RAM are set to their reyuired nonzero values 
as shown below: 
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o The [BREAK! key flag BRKKEY CÖ011] * -1 <false). 

o The top of memory pointer MEMTOP C02E5! = the 1owest 

non—RAM address (froro step 4); MEMTOP will be altered 
later when the Screen Editor is opened in step 15. 

o The bottom of memory pointer MEMLO CÖ2E7! = 070öf MEMLO 

can be changed later i f there is either a dis kette— or 
cassette-boot Operation. 

o The following resident routines are called for initia1ization: 

Screen Editor 
Displag Hand 1er 
Keyboard Hand 1er 
Printer Händler 
Cassette Händler 
Central I/O Monitor (CIO) 

Serial I/O Monitor (SIO) 

Interrupt processor 

o The [START! key is checked« and if pressedi the cassette—boot 

request flag CKEY CQ04A! is set. 

12. 6502 IRQ interrupts are enabled using the CLI Instruction. 

13. The device table HATABS EQ31A3 is initialized to point to the 
resident handlers. See Section 9 for Information relating to 
the Device Händler table. 

14. The cartridge slot addresses for cartridges B and A are 
examined to determine if cartridges are inserted» if RAM does 
not extend into the cartridge address space. 

If the content of location 9FFC is zero* then a JSR is 
executed through the vector at 9FFE, thus initializing 
cartridge "B". The cartridge is expected to return. 

If the content of location BFFC is zero* then a JSR is 
executed through the vector at BFFE/ thus initializing 
cartridge "A“. The cartridge is expected to return. 

15. IOCS #0 is set up for an OPEN of the Screen Editor <E> and 
the OPEN is performed. The Screen Editor will use the highest 
Portion of RAM for the screen and will adjust MEMTOP 
accordingly. If this Operation should failj the entire 

initialization process is repeated. 

16. A delay is effected to assure that a VBLANK Interrupt has 
occurred. This is done so that the screen will be estab1 i shed 
before continuing. 

17. If the cassette-boot request flag is set {see step 11 above)/ 
then a cassette-boot Operation is attempted. See Section 10 
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for details of the cassette-b oa t Operation. 

18. If any of the three conditions stated below enistsi an 
attempt is made to boot from the disk, 

There are no cartridges in the slots. 

Cartridge B is inserted and bit 0 of 9FFD is 1. 

Cartridge A is inserted and bit 0 of BFFD is 1. 

See Section 10 for details of the d iskette-boot Operation. 

19. The coldstart flag COLDST is reset to indicate that the 
coldstart process went to completion. 

20. The initialization process is now complete* and the 
Controlling application is noui determined via the remaining 
steps. 

If there is an A cartridge inserted and bit-2 of BFFD is 1* 
then a JMP is executed through the vector at BFFA. 

Qr, if there is a B cartridge inserted and bit-2 of 9FFD is 
1/ then a JMP is executed through the vector at 9FFA. 

Ori a jump is executed through the vector DÖSVEC that can 
point to the blackboard routine (default case)* cassette 
booted Software or diskette booted Software. DOSVEC can be 
altered bg the booted Software as explained in Section 10. 


SYSTEM RESET INITIALIZATION (WARMSTART> PROCEDURE 

The functions listed below are performedi in the order shotun. as 
part of the System reset initialization process: 

A. Same as power-up Step 1. 

B. The Warmstart flag WÄRMST C00083 is set to -1 (true). 

C. Same as powei—up steps 3 through 5. 

D. OS RAM is zeroed from locations 020G-03FF and 0Q1Q-007F. 

E. Same as power-up steps 9 through 16. 

F. If a cassette-boot was successfully completed during the 

power—up initialization > then a JSR is executed through the 
vector CASINI 100023. See Section 10 for details of the 
cassette-boot process. 
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G. Same as power-up s tep 18* except instead of booting the 
diskette Software, a JSR is executed through the vector DOSINI 
COOOC J i f the di s kette—boot was successfully c otnp leted during the 
Power-up initialization. See Section 10 for details of the 

diskette—boot process. 

H. Same as power-up steps 19 and 20. 

Note that the initialization procedures and main entries for all 
Software entities are executed at every System reset as well as 
at power up <see steps 14, 17, 18, 20, F and GJ. If the 

user-supp1ied initia1ization/startup code must behave differently 
in response to System reset than it does to power—up, then the 
Warmstart flag WARNST E00083 should be interrogatedi WARNST = 0 
means power-up entry, eise System reset entry. 
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8 FLOATING POINT ARITHMETIC PACKAGE 


This section describes the BCD floating point (FP) package that 
is resident in the OS ROH in both the models 400 and 800. 


The floating point package maintains numbers interna 1ly as A-byte 
quantities: a 5-byte ( 10 BCD digit) mantissa with a 1—byte 
exponent. BCD internal representat i on was chosen so that decimal 
division would not lead to the rounding errors typically found in 
binary representation imp1ementations. 


The package provides the following operations: 

ASCII to FP conversion. 

FP to ASCII conversion. 

Integer to FP conversion. 

FP to integer conversion. 

FP add» subtract» multiply»and divide. 

FP logarithm, exponentiation» and polynomial evaluation. 
FP zero. load, störe» and move. 

A floating point Operation is performed by calling one of the 
provided routines (each at a fixed address in ROM> after having 
set one or more -floating point pseudo registers in RAM. The 
result of the desired Operation will also involve floating point 
pseudo registers. The primary pseudo registers are described 
below and their addresses given within the square brackets: 
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FRO COOD43 * 

FR1 cooeo: = 
FLPTR CÖÖFC3 = 

INBUFF EOOF33 = 

CIX COOF23 = 

LBUFF E05803 * 


6-byte internal form of FP number. 
6-byte internal form of FP number. 
2-byte pointer < lo, h i > to a FP. 
number. 

2-byte pointer (loihi) to an ASCII text 
buffer. 

1-byte indexj used as offset to buffer 

pointed to by INBUFF. 

result buffer for the FASC routine. 


FUNCTIONS/CAUL ING SEQUENCES 

Descriptions of these floating point routines assurne that 
a pseudo register is not altered by a given routine. The 
numbers in square brackets Exxxxl are the ROM addresses of the 
routines. 


ASCII to Floating Point Conversion (AFP) 

Function: This routine takes an ASCII string as input and 
produces a floating point number in internal form. 

Galling sequence: 

INBUFF *= pointer to buffer containing the ASCII 
representation of the number. 

CIX = the buffer offset to the first byte of the ASCII 
number. 

USR AFP E08003 

BCS first byte of ASCII number is invalid 

FRO = floating point number. 

CIX = the buffer offset to the first byte after the ASCII 
numb er. 

Algorithm: The routine takes bytes from the buffer until it 
encounters a byte that cannot be part of the number. The bytes 
scanned to that point are then converted to a floating point 
number. If the first byte encountered is invalidi the carry bit 
is set as a flag. 


Floating Point to ASCII Conversion (FASC) 

Function: This routine converts a floating point number from 
internal form to its ASCII representation. 
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Calling sequence: 


FRO = Floating point number. 

JSR FASC CD8E63 

INBUFF = pointer ta the first byte of the ASCII number. 

The last byte of the ASCII representation has the most 
significant bit <sign bit) set; no EOL follous. 

Algorithm: The routine converts the number from its internal 
floating point representation to a printable form (ATASCII). The 
pointer INBUFF uill point to part of LBUFF/ where the result is 
stör ed. 


Integer to Floating Point Conversion (IFP) 

Function: This routine converts a 2-byte unsigned integer (Ö to 
65535) to floating point internal representation. 

Calling sequence: 

FRO = integer (FRO+O = LSB, FRO+1 = MSB). 

JSR IFP ED9AA3 

FRO = floating point representation of integer. 


Floating Point to Integer Conversion (FPI) 

Function: This routine converts a positive floating point number 
from its internal representation to the nearest 2-byte integer. 

Calling sequence: 


FRO — floating point number. 

JSR FPI CD9D2J 

BCS FP number is negative or >- 65535.5 


FRO = 2-byte integer (FRO+O = LSB, FRO+1 = MSB). 

Algorithm: The routine performs true rounding, not truncation, 
during the conversion process. 
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Floating Point Addition (FADD> 


Function: Th i s routine adds tum floating point numbers and checks 
the result for out-of-range. 

Galling sequence: 

FRO = floating point number. 

FR1 = floating point number. 

JSR FADD CDA&63 

BGS out-of-range result. 

FRO - result of FRO + FR1, 

FR1 is altered. 


Floating Point Subtraction (F5UB) 

Function: This routine subtracts tum floating point numbers and 
checks the result for out-of-range. 

Galling sequence: 

FRO = floating point minuend. 

FR1 = floating point Subtrahend. 

JSR FSUB CDA601 

BCS out-of-range result. 

FRO = result of FRO - FR1. 

FR1 is a1tered. 


Floating Point Multip1ication (FMUL) 

Function: This routine ntuItiplies tum floating point numbers and 
checks the result for out-of-range. 

Cal1ing sequence: 

FRO = floating point multiplier. 

FR1 = floating point multiplicand. 

JSR FMUL CDADB1 

BCS out-of-range result. 

FRO * result of FRO * FR1, 

FR1 is altered. 
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Floating Point Division (FDIV) 


Function: This routine divides tuo floating point numbers and 
chects for division by zero and for result aut-of-range. 

Galling sequence: 

FRO - -Floating point dividend. 

FRi * floating point divisor. 

JSR FDIV CDB281 

BGS out-of-ränge result or divisor is zero. 

FRO = result of FRO / FRI. 

FRI is altered. 


Floating Point Logarithms (LOG and LOGIO) 

Function: These routines take the natural or base 10 logarithms 
of a floating point number. 

Calling sequence: 

FRO — floating point number. 

JSR LOG CDECD1 for natural logarithm 

or 

JSR LOGIO CDED11 for base 10 logarithm 

BCS negative number or overflout. 

FRO = floating point logarithm. 

FRi is altered. 

Algorithm: Botb logarithms are first computed as base 10 
logarithms using a 10 term po1ynomia1 approiimation; the natura 1 
logarithm is computed by dividing the base 10 result by the 
constant LOGlO(e). 

The logarithm of a numb er Z i s c ompu ted as f o 1 louts : 

F •» (10 ** Y> = Z where 1 <= F < 10 (norma 1 i zat ion). 

L = LOGIO(F> by 10 term polynomia1 appro ximation. 

LOGIO(Z) - Y + L. LOG(Z) = LOGIO(Z) / LOGlO(e). 

NOTE: This routine does not return an error if the numb er inp ut 
is zero; the LOGIO result in this case is approximate1y —129.5, 
uh ich is not useful. 
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Floating Point Exponentiation (EXP and EXPIO) 

Function: This routine sxponentiates. 

Galling seq.uence: 

FRO — floating point exponent <Z). 

JSR EXP CDDC03 for e **• Z 

or 

JSR EXPIO CDDCC3 for 10 Z 

8CS overflouj. 

FRO — -Floating point result. 

FR 1 is a 1tered. 

Algorithm: Both exponentials are computed internally as base 10i 
tuith the base e exponential using the identitg: 
e ** X = 10 ** ( X * L0G10<e> ). 

The base 10 exponential is evaluated in tmo parts using the id entity 

10 ** X = 10 ** (I + F) = (10 ** 1) * <10 F> — tirhere I is the 
integer portion of X and F is the fraction. 

The term 10 F is evaluated using a polynomial appr o x ima t i om 
and 10 I is a straightfortuard mod i -f i cat i on to the -floating 
point exponent. 


Floating Point Polynomial Evaluation (PLYEVL) 

Function: This routine performs an n degree polynomial 
evaluation. 

Calling sequence: 

X,Y = pointer (X = LSB) to list of FP coefficients <A(i>) 
ordered from high order to lotü order (six bytes per 
coefficient). 

A = number of coefficients in list. 

FRO - floating point independent variable <Z). 

JSR PLYEVL CDD401 

BGS overflow or other error. 

FRO = resu 11 of A(n)*Z**n + A(n-1>*Z**n~l ... + A(i)*Z + 
A(Q). 

FR1 is altered. 

Algorithm: The polynomial P(Z) = SUM<i=0 to n> (A(i)#Z#*i) is 
computed using the Standard method shoun beloui: 

P(Z > = <. . . (A(n >*Z + A(n-1)>*Z + ... + A(1))*Z + A<0> 
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Clear FRO (ZFRO) 


Function: This routine sets the contents of pseudo register FRO 
to all zeros. 

Galling sequence: 

JSR ZFRO CDA443 

FRO « zero. 


Clear Page Zero Floating Point Number (ZF1) 

Function: This routine sets the contents of a zero-page floating 
point number to all zeroes. 

Calling sequence: 

X st Zero-page address of FP number to clear. 

JSR ZF1 EDA463 

Zero-page FP number(X) = zero. 


Load Floating Point Number to FRO <FLDOR and FLDÖP> 

Function: These routines load pseudo register FRO uzith tr:e 
floating point number specified by the calling sequence. 

Calling sequences: 

X.Y = pointer (X = LSB) to FP number. 

JSR FLDOR CDD893 

or 


FLPTR = pointer to FP number. 

JSR FLDOP CDD8D3 

FRO = floating point number (in either case). 
FLPTR » pointer to FP number (in either case). 
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Load Floating Point Number to FR1 (FLD1R and FLD1P> 


Function: These routines load pseudo register FR1 uiith the 
Floating point number specified by the calling seguence. 

Ca Hing seguenc es: 

As in prior description, except the result goes to FR1 
instead of FRO, FLD1R CDD783 and FLD1P CDD9C3. 


Store Floating Point Number From FRO (FSTOR and FSTOP) 

Function: These routines störe the contents of pseudo register 
FRO to the address specified by the calling seguence: 

Calling seguence: 

As in prior descriptions f except the floating point number 
is stored from FRO rather than loaded to FRO. FSTOR CDDA73 
and FSTOP CDDAB3. 


Move Floating Point Number From FRO to FR1 (FMQVE) 

Function: This routine moves the floating point number in FRO to 
pseudo register FR1. 

Calling seguence: 

JSR FMÜVE CDDB63 

FRi = FRO (FRO remains unchanged). 


RESOURCE UT1LIZATIQN 

The floating point package uses the follofuing RAN locations in 
the course of performing the functions described in this section 

00D4 through OOFF 
057E through 05FF 

All of these locations are available for program coding 
if your program does not call the floating point package. 
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IMPLEMENTATION DETAILS 


Floating point numbers are maintained internally as 6-byte 
guantities, with 5 bytes (10 BCD digits) of mantissa and 1 byts 
of exponent. The mantissa is always normalized such that the 
most significant byte is nonzero (note "byte“ and not "BCD 
d i g i t" >. 


The most significant bit of the exponent byte provides the sign 
for the mantissa; 0 for positive and 1 for negative. The 
remaining 7 bits of the exponent byte provide the exponent in 
excess A4 notation. The resulting number represents pouers of 100 
decimal (not powsrs of 10). This storage format allows the 
mantissa to hold 10 BCD digits when the value of the exponent is 
an even pouer of 10, and 9 BCD digits uihen the value of the 
exponent is an odd power of 10. 

The implied decimal point is aiiuays to the immediate right of the 
first byte. An exponent less than 64 indicates a number less than 
1. An exponent egual to or greater than 64 represents a number 
equal to or greater than 1. 

Zero is represented by a zero mantissa and a zero exponent. To 
test for a result from any of the Standard routines; test either 
the exponent or the first mantissa byte for zero. 

The absolute value of floating point numbers must be greater than 
10#*—98, and less than 10**+98, or be egual to zero. There is 
perfect symmetry between positive and negative numbers with the 
exception that negative zero is never generated. 

The precision of all computations is maintained at 9 or 10 
decimal digits, but accuracy is somewhat less for those functions 
involving polynomial approximations (logarithm and 
exponentiation>. Also, the Problems inherent in all floating 
point Systems are present here; for example: subtracting tuio very 
nearly equal numbers, adding numbers of disparate magnitude, or 
successions of any Operation, will all result in a loss of 
significant digits. An analysis of the data ränge and the order 
of evaluation of expressions may be reguired for some types of 
applications. 

The examples below compare floating point numbers with their 
internal representations, as an aid to understanding storage 
format. All numbers prior to this point have been expressed in 
decimal notation, but these examples will use hexadecimal 
notation. Note that A4 decimal (the excess number of the 
exponent) is 40 when expressed in hexadecimal: 

Number: +0.02 = 2 # io**-2 = 2 * 100**-1 

Stored: 3F 02 00 00 00 00 (FP exponent = 40 - 1) 

Number: -0.02 = -2 * 10**-2 * -2 # 100*#-! 

Stored: BF 02 00 00 00 00 (FP exponent « 80 + 40 - 1) 
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Number 
Stored: 

Number: 
Stored 

Number: 
Stored: 


+37.0 - 3. 7 * 10**1 = 37 * 100**0 
40 37 00 00 00 00 (FP exponent = 


-4.60312486 
05 46 03 01 


* 10**11 = “46. 03. . . 
24 86 <FP exponent = 


0 . 0 

00 00 00 00 00 00 


(special case) 


40 + 0 ) 
100**5 

80+40+5) 
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9 ADDING NEW DEVICE HANDLERS/PERIPHERALS 


Th is sec tion describes the interface requirements for a 
nonres ident Device Hand 1er that is t o be accessed via the Centra1 
I/O utility (CIO). The Serial bus I/□ utility <SIO> interface is 
defined for those handlers that utilize the Serial I/O bus. 

The I/Ö subsystem is organized uiith three levels of Software 
between you and your hardware: The CIO, the individual device 
handlers, and the SIö. 

The CIO performs the following functions: 


Logical device name to Device Händler mapping (on OPEN), 

I /Q Control Block < IOCB ) rna inte na nee. 

Logical record handling. 

User buffer handling. 

The device handlers are beloui CIO. They perform the 
following functions: 

Device initia1ization on pouer-up and System reset. 

Device-dependent support of OPEN and CLOSE commands. 
Byte-at-a-time data input and output. 

Devic e-dependent special operations. 

Device-dependent command support, 

Device data buffer management. 

The SIO is at the bottom leve1 (for Serial I/O bus peripheral 
handlers). It performs the following functions: 

Control of all Serial bus I/O, conforming to the bus 
protoco I. 

Bus Operation retries on errors. 

Return of unified error statuses on error conditions. 
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A separate control structure is used -Por communieation at each 
interface* as follous: 

User/CIO I/O Control Block <IOCB) 

CIO/Handler Zero-page IOCB < ZIOCBi 

Handler/SIQ Device Control Block (DCB> 
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Wh ere:-shows a control path, 

4**4 shows the data structure required for a path. 

Note the following: 


1 , The 
SIO. 

2 , The 

3 , The 

Figure 9-1 


Keyboard/Disp 1 ay/Screen Editor handlers don / t use 

Diskette Händler cannot be called directly from CIO. 
DCB is shotun ttuice in the diagram. 

I/O Subsystem Flow Diagram 
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DEVICE TABLE 


The device table is a RAM-resident table that contains the 
s ing 1 e-character device name ( e. g. Kr D* Cr etc), and the 
handl er address for each of the handl ers known to CIO. The 
table is initialized to contain entries f or the fol1owing 
resident handlers; Kegboard CK)/ Display CS)/ Screen Editor 
CE)r Cassette (C)r and Printer (P) at power-up and System reset. To 
install a new handler< some procedura must insert a device table entry 
after the table is initialized. 

The table Format is shown belout: 


HATABS C031A3 


+ - 

! device name 

+- 

i handler vector 
+ 

i table address 

+ - 

! more 

! entries 

+ "— ——— 

i zero fi11 to 

' end of table 
+- 


+ 

t 

+ 


SS 


+ 



I 


+- one entry 



Figure 9-2 Device Table Format 


Th i s 38—by te table will hold a maximum of 12 entriesr uiith the 
last 2 bytes being zero. CIO scans the table from the end to 
the beginn ing (high to louj address)/ so the entry nearest the 
end of the table will take precedence in case of multiple 
occurrences of a device name. . 

The device name for each entry is a single ATASCII character/ and 
the handler address points to the handler's vector table* that 
will be described in the following section. 


CIQ/HANDLER INTERFACE 

This section describes the interface between the Central I/O 
Utility and the individual device handlers that are represented 
in the Device Table (as described in the preceding section). 
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Galling Mechanism 

Each handler has a vector table as shouin below: 


+ OPEN vector + 

+ - + 

+ CLOSE vector + 

+ - + 

+ GETBYTE vector + 

+ - + 

+ PUTBYTE vector + 

+-+ 

+ GETSTAT vector + 
— —+ 
+ SPECIAL vector + 

+ - + 

+ JMP init code + 
+ + 
+-+ 


(lotu address) 


(high address) 


Figure 9-3 Handler Vector Table 

The device table entry Tor the handler points to the first 
byte of the vector table. 

The first six entries in the table are vectors <lo,hi) that 
contain the address - 1 of the handler routine that handles 
the indicated funetion. The seventh entry is a 6502 JMP 
instruction to the handler initialization routine. CIO uses 
only the addresses contained in this table for handler entry. 
Each user/CIO command translates to one or more calls to one 
of the handler entries defined in the vector table. 

The vector table provides the handler addresses for certain 
fixed functions to be performed to CIO. In addition* Operation 
Parameters also must be passed for most functions. Parameter 
passing is accomplished using the 6502 At X» and Y registers 
and an IOCB in page O named ZIÜCB E00203. In generali register 
A is used to pass data, register X contains the index to the 
originating IOCBi and register Y is used to pass Status 
information to CIO. The zero—page IGCB» is a copy of the 
originating IOCBi but in the course of Processing some 
commands, CIO can alter the buffer address and buffer length 
Parameters in ZIQCB, but not in the originating IOCB (see 
Section 5 for information relating to the originating IOCB). 

See Appendix B for the Standard Status byte values to be 
returned to CIO in register Y. 
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The following sections describe the Clü/handler interface for 
each of the vectors in the hand1 er vector table. 


Händler Initialization 

NOTE: This entry doesn't appear to have any function for 

nonresident handlers due to a bug in the current QS — the 
device table is cleared in response to System reset as 
well as power-up. This prevents this entry point from ever 
being called. The rest of this section discusses the 
intended use of this entry point. Conformation would be in 
order to allow compatibi1ity with possible corrected 
versions of the OS in the future. 

The entry was to have been called on all occurrences of 
powei—up and System reset; the handler is to perform 
initia1ization of its harduare and RAM data using a routine 
that assures proper processing of all CIO commands that follow. 


Functions Supported 

This section describes the functions associated with the first 
six vectors from the handler vector table. This section also 
presents a brief, device-independent description of the 
C10/hand1 er interface and recömmended actions for each function 
vector. 


OPEN 

This entry is called in response to an OPEN command to CIO. The 
handler is expected to validate the OPEN Parameters and perform 
any required device initia1ization associated with a device OPEN. 

At handler entry, the following Parameters can be of interest: 

X = Index to originating IOCB. 

Y = *92 (status = function not implemented by handler). 

ICDNOZ E00213 = device number (1-4, for muItiple device 

handlers). 

ICBALZ/ICBAHZ C0024/00253 = address of device/fi1ename 

specification. 

ICAX1Z/ICAX2Z COÖ2A/0O2B3 = device-specific Information. 

The handler attempts to perform the indicated OPEN and 
indicates the status of the Operation by the value of the Y 
register. The responsibi1ity for checking for multiple OPENs to 


136 


ÜPERATING SYSTEM C016555 — Section 9 


the same device or file, where it is illegal, lies with the 
handler. 


CLOSE 

This vector table entry is called in response to a CLOSE command 
to CIO. The handler is expected to release any held resources 
that relate specifically to that device/filename, and for output 
files to: 

1) send any data remaining in handler buffers to the device, 

2) mark the end of file 

3) update any associated directories, allocation maps, etc. 


At handler entry, the following parameters can be of interest: 
X = index to originating IOCB. 

Y = 492 <status = function not implemented by handler). 

ICDNOZ C00213 = device number (1-4, for multiple device 

hand1 ers ). 

ICAX1Z/ICAX2Z C0Ö2A/OO2B3 = device-specific information, 

The handler attempts to perform the indicated CLOSE and 
indicates the status of the Operation by the value of the Y 
register. 

CIO releases the associated IOCB after the handler returnsi 
regardless of the Operation status value. 


GETBYTE 

This vector table entry is called in response to a GET 
CHARACTERS or GET RECORD command to CIO. The handler is 
expected to return a single byte in the A register, or return an 
error status in the Y register. 

At hand1er entry, the following parameters can be of interest: 

X = index to originating IOCB. 

Y = 492 (status = function not implemented by handler). 

ICDNOZ 100211 = device number (1-4, for multiple device handlers). 
ICAX1Z/ICAX2Z C002A/002B1 = device-specific information. 

The handler will obtain a data by<te directly from the device or from a 
handler-maintained buffer and return to CIO with the byte in the 
A register and the Operation status in the Y register. 
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Händlers that da not have short timeouts associated with the 
reading cf data (such as the Keyboard and Cassette Händlers)! 
must monitor the CBREAK3 key flag BRKKEY tOOl 1 3 and return with a 
status of $80 when a CBREAK3 condition occurs. See Appendix Li 
E5; and Section 12 for a discussion ofCBREAK3 key monitoring. 

CIO cbecks for reads from device/files that have not been opened 
or have been opened for output only, the handler will not be cai led in 
those cases. 


PUTBYTE 

This entry is called in response to a PUT CHARACTERS or PUT 
RECORD command to CIO. The handler is expected to accept a single 
byte in the A register or return an error status in the Y 
register. 

At handler entry, the following Parameters can be of interest: 

X = index to originating IOCB. 

Y = $92 (status = function not implemented by handler). 

A - data byte. 

ICDNOZ £00213 = device number (1-4, for mu11ip1e device 

handlers). 

ICAX1Z/ICAX2Z CÖ02A/0Ö2B3 — device—specific Information. 

The handler sends the data byte directly to the device, or to a 
hand ler—ma inta ined buff er, and return s to CIO with the Operation 
status in the Y register. If a handler-maintained buffer fills, 
the handler will send the buffered data to the device before 
returning to CIO. 

CIO checks for WRITEs to device/fi1 es that have not been opened, 
or have been opened for input only. The handler uiill not be called in 
those cases. 

Nou that the normal Operation of PUTBYTE has been defined, a 
special case must be added. Any hand1er that will operate within 
the environment of the ATARI 8K BASIC language interpreter has a 
different set of rules. Because BASIC can call the handler 
PUTBYTE entry directly, without going through CIO, the zero-page 
IOCB (ZIQCBJ can or may not have a relation to the PUTBYTE call. 
Therefore, the handler must use the outer level IOCB to obtain 
any Information that would normally be obtained from ZIOCB. Note 
also that the OPEN protection normally provided by CIO is 
bypassed (i.e. PUTBYTE to a non-OPEN device/file and PUTBYTE to a 
read-only OPEN). 
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This entry is called in response to a GET STATUS command to CIO. 

The handler is expected to return four bytes of status to memory 
or return an error status in the Y register. 

At handler entry* the following parameters can be of interest: 

X = index to originating IOCB. Y — $92 (status = function not 
implemented by handler). 

ICDNOZ £00213 = device number (1-4* for multiple device handlers). 

ICBALZ/ICBAHZ C0024/0Q25D = address of 
device/filename specification. 

ICAX1Z/ICAX2Z 

C002A/002B3 = device-specific Information. 

The handler gets device status Information from the device 
Controller and puts the status bytes in DVSTAT £02EA3 through 
DVSTAT+3* and finally returns to CIO with the Operation status 
in register Y. 

The IOCB need not be opened nor closed in Order for you 
to request CIO to perform a GET STATUS Operation; the hand1 er 
must check where there are restrictions. See Section 5 for a 
discussion of the CIO actions involved üiith a GET STATUS 
Operation using both open and closed IOCB 's* and note the impact 
of this operation on the use of the buffer address parameter. 


SPECIAL 

This handler entry is used to support all functions not handled 
by the other entry points* such as diskette file RENAME* display 
DRAW* etc. Specifically* if the IOCB command byte value is 
greater than $OD* then CIO will use the SPECIAL entry point. The 
handler must interrogate the command byte to determine if the 
requested Operation is supported. 


At handler entry* the following parameters can be of interest: 
X = index to originating IOCB. 

Y s* *92 (status = function not implemented by handler). 


ICDNOZ £00213 

ICCOMZ 100223 
ICBALZ/ICBALH 
ICBLLZ/ICBLHZ 
ICAX1Z/ICAX2Z 


= device number (1-4* for multiple device 
handlers). 

= command byte, 

£0024/00253 = buffen address. 

£0028/00293 = buffer length. 

I0Ö2A/002B3 = device-specific information. 
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The Händler will perform the indicated Operation, if possible, 
and return to CIO with the Operation Status in register Y. 


The IOCB need not be opened nor closed in order for you 
to request CIO to perform a SPECIAL Operation; the Händler 
must check uhers there are restrictions, See Section 5 for a 
discussion of the CIO actions involved with a SPECIAL 
Operation using both open and closed lOCB's, and note the 
impact of this on the use of the buffer address parameter. 


Error Handling 

Error Handling has been simplified somewhat by having CIO handle 
outer level errors and having SIO handle Serial bus errors, 
leaving the Händler to process the remaining errors These 
errors include: 

out-of-range Parameters. 

CBREAK1 key abort. 

Invalid command. 

Read after end of file. 

The current Händlers respond to errors using the following 
guidelines: 


They keep the recovery simple (and therefore predictable and 
rep eatable >, 

They Do not interact directly with you for recovery 
instruc tions. 

They lose as little data as possible. 

They make all attempts to maintain the integrity of'file 
oriented device storage — this involves the initial design 
of the structural elernents as well as error recovery 
techniques. 


Resource Allocation 

Nonresident Händlers needing code and/o? data space in RAM should 
use the techniques listed below, to assure nonconflict with other 
parts of the OS, including other nonresident Händlers. 
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Zero-Page RAM 


Zero-page RAM has no spare bytes, and even if there uersi ttiere 
is no allocation schems to Support multiple program assignment of 
the spares. Therefore, the nonresident Händler must save and 
restore tHe bytes of zero-page RAM it is going to use. The bytes 
to use must be chosen carefully, according to the follouing 
eriteria: 

The bytes cannot be accessed by an interrupt routine. 

The bytes cannot be accessed by any noninterrupt code 
betueen the time the Händler modifies the bytes and then 
restores the original values. 

A simple save/restore technique utould utilize the stack in a 
mann er similar to that shown be 1 otu: 


LDA 

COLCRS 

; (for s xample i 

PHA 


i SAVE ON STACK. 

LDA 

PHA 

COLCRS+1 


LDA 

HPOINT 

i HANDLER'S POINTER. 

STA 

COLCRS 


LDA 

HPGINT+1 


STA 

COLCRS+1 


XXX 

(COLCRS),Y 

; DO YOUR POINTER THING 

PLA 


i RESTORE OLD DATA. 

STA 

PLA 

COLCRS+1 


STA 

COLCRS 



Note that the Display Händler or Screen Editor should not be 
called before restoring the original value of COLCRS, because 
COLCRS is a variable used by those routines. 

Non zero-Page RAM 

There is no allocation scheme to support the assignment of 
fixed regions of nonzero-page RAM to any specific process, so the 
handler has three choices; 

1. Make a dynamic allocation at initia1ization time by 
altering MEMLQ C02E71. 

2. Include the variables with the handler for RAM-resident 
Händlers. This still involves altering MEMLO at the time 
the handler is booted. 

3. If the handler replaces one of the resident Händlers <by 
removing the resident handler's entry in the device 
tablei, then the new handler can use any RAM that the 
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formerly resident handler would have used. 


Stack Space 

In most cases. there are no restrictions on the use of the stack 
by a handler. However, if the handler plans to push more than a 
couple dozen bytes to the stack; then it should do a stack 
overflow test* and always leave stack space for Interrupt 
Processing. 


HANDLER/SIO INTERFACE 

This section describes the interface between serial bus device 
handlers and the serial bus I/O utility (SIO). SIO completely 
hand les all bus transac t i ons f o 1 lowing the device —independent bus 
protocol. SIO is responsible for the following functions: 

Bus data format and timing from Computer end. 

Error detectioni retries and statuses. 

Bus timeout. 

Transfer of data between the bus and the caller 's buffer. 


Galling Mechanism 

SIO has a single entry point SIOV CE4593 for all operations. The 
device control block (DCB) EG30Ö3 contains all Parameters passed 
to SIO. The DCB contains the following bytes: 

DEVICE BUS ID — DDEVIC C03003 

The bus ID of the device is set by the handler prior to calling 
SIO (see Appendix I). 

DEVICE UNIT # — DUNIT CQ301] 

This byte indicates that of n units of a given device type to 
access f and is set by the handler prior to calling SIO. This 
value usually comes from ICDNÖZ. SIO accesses the bus device 
whose address is equal to the value of DDEVIC plus DUNIT minus 1 
(the 1 owest unit number is norma11y equa1 to 1>, 

DEVICE COMMAND — DCOMND CQ3023 

The handler sets this byte prior to calling SIO. It will be sent 
to the bus device as part of the command frame, See Appendix I 
for device command byte values. 
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DEVICE STATUS 


DSTATS E03033 


This byte is b i d ir ec t i ona 1. The handler will use DSTATS to 
indicate to SIO what to do after tbs command frame is sent and 
acknowledged. SIO ui i 11 use it to indicate to the h and ler the 
Status of tbe requested Operation. 

Prior to an SIO call: 

7 0 

+—i—i—i—i—i—^— y—y 
i WiR! unused i 

+—j.—,-|-|- y —J.—— f. 

Where: W,R = 0.0 indicates no data transfer is associated tuifch the 

Operation. 

0.1 indicates a data frame is expected from the device 
1.0 indicates a data frame is to be sent to the device 
1i1 is inva1id. 


After an SIO call: 

7 0 

h— y — y —i— y —i—i —-+—y 
I status code i 

+-,-,-j-|-|-- y -(. 

See Appendix C for the possible SIO Operation status codes. 

HÄNDLER BUFFER ADDRESS — DBUFL0/D8UFHI C0304/03Q53 

The bandler sets this 2-byte pointer. It indicates the source 
or destination buffer for device data or status Information. 

DEVICE TIMEOUT — DTIMLO E03063 

The handler sets this byte. It specifies the device timeout time 
in units of 64/60 of a second. For example. a count of 6 
specifies a timeout of 6.4 seconds. 

BUFFER LENGTH/BYTE COUNT — DBYTLO/DBYTHI £0308/03093 

The handler sets this 2-byte count for the current 
Operation, and indicates the number of data bytes to be 
transferred into or out of the buffer. This parameter is not 
required if the STATUS byte W and R bits are both zero. These 
values indicate that no data transfer is to take place. 

WARNING: There is a bug in SIO that causes incorrect 
actions tuhen the last byte of a buffer is in a ntemory 
address ending in $FF. such as 13FF, 42FF. etc. 
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AUXILIARY INFORMATION — DAUX1/DAUX2 C030A/030B1 


The handler sets these 2-bytes. The SIO includes them in the bus 
command frame; they have device-specific meanings. 


Functions Supported 

SIO does not examine the COMMAND byte it sends to the device> 
because all bus transactions are expected to conform to a 
universal protocol. The protocol includes three formsi stated 
below <as seen from the Computer): 

Send command frame. 

Send command frame and send data frante. 

Send command frame and receive data frame. 

The values of the W and R bits in the status byte select the 
command form. 


Error Hand 1 ing 

SIO handles most of the serial bus errors for the handler/ 
as indicated below: 

Bus timeout — SIO provides a uniform command frame and data 
frame ACK byte timeout of 1/60 of a second - 0 / + 1/60. 

The handler specifies the maximum CÜMPLETE byte timeout 
value in DTIMLO. 

Bus errors SIO detects and reports UART overrun and 
framing errors. The sensing of these errors in any received 
byte will cause the entire associated frame to be considered 
bad. 

Data frame checksum error — SIO validates the checksum on 
all received data frames and generates a checksum for all 
transmitted frames. 

Inva1id response from device — In addition to the error 
conditions stated above/ SIO checks that the ACK and 
CDMPLETE responses are proper <ACK = *41 and COMPLETE = 

*43). ACK Stands for acknowledge. 

Bus operation retri es — SIO will attempt one complete c ommand 
retry if the first attempt is not error free« where a complete 
command try consists of up to 14 attempts to send <and 
acknowledge) a command frame/ followed by a single attempt to 
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receive the COMPLETE code and possibly a data frame. 

NOTE: There is a bug in the retry logic for data writes/ 
such that if the command frame is acknowledged by the 
c entroll er« bu t the data frame i s not ac fcnourled g ed / then SIO 
will retry indefinitely. 

Unified error status Codes — SIO provides device-independent error 
codes (see Appendix C>. 


SERIAL I/O BUS CHARACTERISTICS AND PROTOCOL 
This section describes: 

o The electrical characterist i cs of the ATARI 400 
and ATARI 800 Home Computers serial bus 

o The use of the bus to send bytes of data/ 

o The Organization of the bytes as "frames" (records)» 

o The overall command sectuences that utilize frames 

and response bytes to provide Computer/periphera1 communication. 


Har dwar e/El ec tr ica 1 Charac ter ist i c s 

The ATARI 400 and the ATARI 800 Home Computers 
communicate with peripheral devices over a 19/200 baud 
asynchronous serial port. The serial port consists of a serial 
DATA OUT <transmissian> line ( a serial DATA IN (receiver) line 
and other miscellaneous control l ines. 

Data is transmitted and received as 8 bits of serial data <LSB 
sent first) preceded by a logic zero start bit and succeeded 
by a logic one stop bit. The serial DATA OUT is transmitted as 
positive logic (+4v — one/tr ue/h i gh / Ov = zero/f al se/loui). The 
serial DATA OUT line aluiays assumes its new state uhen the 
serial CLOCK OUT line goes highi CLOCK OUT then goes low in 
the center of the DATA OUT bit time. 

An end view of the Serial bus connector at the Computer or 
peripheral is shown beiaui (the cable connectors wou 1 d of 
course be a mirror image): 
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o 

1 


2 4 6 8 10 12 

o o o o a o 

o O O 0 o o 

3 5 7 9 11 13 


uihere: 1 = Computer CLOCK IN. 

2 = Computer CLOCK OUT. 

3 = Computer DATA IN. 

4 = GND. 

5 - Computer DATA OUT. 

6 = GND. 

7 = COMMAND- 

8 = MOTOR CONTROL. 

9 = PROCEED- 

10 * +5v/READY. 

11 - Computer AUDIO IN. 

12 = +12v. 

13 = INTERRUPT-, 

Figure 9—4 Serial Bus Connector Pin Descriptions 


CLOCK IN is not used by the present OS and peripherals. This 
line can be used in future synchronous Communications schemes. 

CLOCK OUT is the serial bus clock. CLOCK OUT goes high at the 
start of each DATA OUT bit and returns to loui in the middle of 
each bit. 

DATA IN is the serial bus data line to the Computer. 

Pin 4 GND is the signa1/shield ground line. 

DATA OUT is the serial bus data line from the Computer. 

Pin 6 GND is the signa1/shield ground line. 

CQMMAND- is normally high and goes loui when a command frame is 
being sent from the Computer. 

MOTOR CONTROL is the cassette motor control line (high^on. 
low= off). 


PROCEED is not used by the present OS and peripherals; this line 
is pulled high. 

+5v/READY indicates that the Computer is turned on and ready. This 
line can also be used as a +5 volt supply of 50ma current rating 
for ATARI peripherals only. 

AUDIO IN accepts an audio Signal from the cassette. 
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+12V is a +12 volt supply of unknown current rating for ATARI 
peripherals only. 

INTERRUPT- is not used by the present OS and peripherals. this 
line is pulled high. 

There are no pin reassignments made in the Serial bus cab1e. 
so pin 3. the Computer 's DATA IN line. is the peripheral's 
data output linei and similarly for pin 5. 


Serial Port Electrical Specifications 

Perip hera1 inp ut: 

V1H = 2. Ov min. 

V1L = 0. 4v max. 

I1H = 20ua. max. @ V1H = 2. Ov 
HL = 5ua. max. @ V1L * . 4v 

Peripheral output (open collector bipolar}; 

VOL — 0. 4v max. @1.6 ma. 

VOH = 4, 5v min. with external iOOKohm pull-up 
Vcc/READY input: 

V1H = 2. Ov min. @ I1H = lma. max. 

V1L = 0. 4v ma x. 

Input goes to logic zero when open. 


Bus Commands 

The bus protocol specifies that all commands must originate front the 
Computer, and that peripherals will present data on the bus only when 
commanded to. Every bus operation will go to completion before 
another bus Operation is initiated (no overlap >. An error detected at 
any point in the command se^uence will abort the entire sequence. 

A bus Operation consists of the following elements: 

Command frarne from the Computer. 

Acknowledgement (ACK) from the peripheral. 

Optiona 1 data fraute to or from the Computer. 

Operation complete (COMPLETE) from the peripheral. 
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Command Frame 


The serial bus protocol provides for three typ es of coswiands; 1 > 
sendi 2) data receive and 3) immediate (no data — command only). 
There is a common eiement in all three types. a command frame 
consisting of f ive bytes of Information sent from the Computer 
tifhile the COMMAND— line is held lotu. The format of the command 
frame is 
shown belotu: 


+ - 

! device ID 
+- 

! command 

+ - 

i auxiliary #1 


i auxiliary #2 
+- 

! checksum 
+- 

Figure 9-5 Serial Bus Command Frame Format 

The device ID specifies that of the serial bus devices is being 
addressed <see Appendix I for a list of device IDs). 

The command byte contains a device-dependent command (see 
Appendix I for a list of device commands). 

The auxiliary bytes contain more device—dependent Information. 

The checksum byte contains the arithmetic sum of the first four 
bytes (with the carry added back after every addition). 



Command Frame Ac knouiledg e 

The periphera 1 being addressed ttfould normally respond to a 
command frame by sending an ACK byte {*41) to the Computer, if 
there is a problem uiith the command frame. the peripheral should 
not respond. 


Data Frame 
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Follouing the command frante (and ACK) can be an optional data 
frame that is formatted as shown belotu: 


+ - + 

! i 

: e 

I data 


by tes 


S checksum 
-—— — *“■ ■ 




This data frame can originate at the Computer or at the device 
Controller* depending upon the command. Current device 
Controllers expect fixed-length data frames as does the Computer* 
tühere the data frame length is a fixed f unc t ion of the device 
type and command. 

The checksum value in the data frame is the arithmetic sum of all 
of the frame data preceding the checksum* with the carry from 
each addition being added back (the same as for the command 
frame). 

In the case of the Computer sending a data frame to a peripheral* 
the peripheral is expected to send an ACK if the data frame is 
acceptable* and send a NAK ($4E)* or do nothing if the data frame 
is unacceptab1e. See the first flouchart in Section 9. 


Op eration Complete 

A peripheral is also expected to send an operation-CQMPLETE byte 
($43) at the time the commanded Operation is complete. The 
location of this byte in the command sequence for each command 
type is shoum in the timing diagrams in Section 9. If the 
Operation cannot go to normal * error~free c ompletion* the 
peripheral should respond ufith an ERROR byte ($45) instead of 
COMPLETE. 
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Bus Timing 


This seetion provides timing diagrams for the three types of 
command sequences: data send> data receivei and immediate. 


DATA SEND sequence: 

-+ +• 

COMMAND- ! i 

+-+ 


+ - + + - // - + 

DATA OUT < cmnd ! i data ! 

-+frame +-//—+ frame + 


+ — + 

DATA IN ! [ 

- + + 

ACK 


tO tl t2 t3 


DATA RECEIVE sequence: 


- + + 

COMMAND- ! { 

+—-~+ 


+-+ +-+ 
s i \ \ 

+ +—//—+ +- 
ACK CMPL 


t4 t5 


—j. 


DATA 

OUT 

! cmnd i 






~ ^Tr-a«ie + — — *■* 




DATA 

IN 

1 t 

1 t 

1 -1-r- / / 

1 1 1 

i 1 l 

data 
f ranie 

l 

1 



T -t- —*— / / — 

ACK 

CMPL 



tO tl t2 t5 
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IMMEDIATE sequence: 


- + + 

COMMAND- { { 


DATA OUT ! cmnd ! 

-+frame +■ 


DATA IN 


+-+ +-+ 

< t i i 

i t ii 

+ +-//-+ +— 

ACK CMPL 


tO tl t2 t5 


Figurs 9-6 Serial Bus Timing Diagram 


The Computer generates a delay (tO) betueen the lowering of COMMAND 
and the transmission of the first byte of the command frame. 

Computer tO (min) = 750 microsec. 

Computer tO (max) = 1600 microsec. 

peripheral tO (min) » ?? 

peripheral tO (max) = ?? 

The Computer generates a delay (tl) between the transmission of 
the last bit of the command frame and the raising of the COMMAND- 
1 ine. 

Computer t 1 ( min ) = 650 microsec. 

Computer tl (max) = 950 microsec. 

peripheral tl (min) - ?? 

peripheral tl (max) = ?? 

The peripheral generates a delay <t2) betuieen the raising of 
COMMAND- and the transmission of the ACK byte by the peripheral. 

Computer t2 (min) = 0 microsec. 

Computer t2 (max) = 16 msec. 

peripheral t2 (min) = ?? 

peripheral t2 (max) = ?? 
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The Computer generates a delay (t3) betuieen the receipt of the 
last bit of the ACK byte and the transmission of the first bit of 
the data fraise by the Computer. 

Computer t3 (min) = iGOO microsec. 

Computer t3 (max) = 1800 microsec. 

peripheral t3 (min) — *?? 
peripheral t3 (max) = ?? 

The peripheral generates a delay (t4) between the transmission of 
the last bit of the data frame and the receipt of the first bit 
of the ACK byte by the Computer. 

Computer t4 (min) = 850 microsec, 

Computer t4 (max) = 16 msec. 

peripheral t4 (min) - ?? 

peripheral t4 (max) = ?? 

The Peripheral generates a delay (t5) between the the receipt of 
the last bit of the ACK byte and the first bit of the COMPLETE 
byte by the Computer. 

Computer t5 (min) = 250 microsec. 

Computer t5 (max) = 255 sec. (handler-dependent) 

peripheral t5 (min) = ?? 

peripheral t5 (max) = N/A 


HÄNDLER ENVIRONMENT 

Nonresident handlers can be installed in at least three different 
manners: 

1. As booted Software from diskette or cassette. 

2. Resident in a cartridge (A or B). 

3. Doumloaded from a serial bus device. 

This section will discuss the basic mechanisms for handler 
installation for these environments. In Order to fully utilize the 
Information in this section/ you must have read and understood the 
following sections: 


Program environments . Section 3 

RAM region . Section 4 

Memory dynamics. . . Section 4 

System initialization. Section 7 

Adding new device handlers/periphera1s . Section ? 

Program environment and initialization . Section 10 
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Bootable Händler 


The diskette- or cassette-booted Software will insert the 
handler's vector table pointer and name to the device table 
whenever the booted software's initialization entry point is 
entered (on power-up and System res et). Remember that both 
power-up and System reset clear the device table of all but the 
resident hand1er entries. 


Cartridge Resident Händler 

The cartridge Software will insert the handler's vector table 
pointer and name to the device table whenever the eartridge's 
initialization entry point is entered (on power-up and 
System reset). Remember that both power-up and System reset 
clear the device table of all but the resident handler entries» 
therefore the device table must be reestablished by the 
handler-initialization procedure upon every entry. 


FLGWCHARTS 

The following pages contain process flowcharts showing the SIO 
and peripheral actions for the Serial bus command forms. 
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PERIPHERAL'S COMMAND FRAME PROCESSING 
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